home *** CD-ROM | disk | FTP | other *** search
/ Macwelt 1 / Macwelt DVD 1.toast / Web-Publishing / HTML-Editoren / Alpha ƒ / Help / Error Help < prev    next >
Encoding:
Text File  |  2000-10-30  |  10.3 KB  |  315 lines
  1.  
  2. Alpha Error Handlers
  3.  
  4.                                                version: 1.1
  5.                                                created: 04/09/98 {10:32:09 pm} 
  6.                                            last update: 10/23/00 {06:14:43 pm} 
  7.  
  8. _________________________________________________________________
  9.  
  10. INTRODUCTION
  11.  
  12. This package provides a uniform mechanism for catching, handling, and
  13. displaying errors.  The key to all this functionality is the try construct,
  14. similar to that available in C++ or AppleScript.  The default error handler
  15. will display any errors in accordance with the current user preferences, in
  16. "Config --> Preferences --> Errors".  See the file "error.tcl" for the
  17. actual procedures.
  18.  
  19. Errors can be reported in one of four levels of detail:
  20.  
  21.     taciturn: display the error message in the message bar.
  22.     
  23.     terse: display the error message in a dialog.
  24.     
  25.     verbose: display the error message and the error code in
  26.         a dialog.
  27.     
  28.     pedantic: display the error message, the error code, and
  29.         whatever context is available through errorInfo in
  30.         a window.
  31.     
  32. A fifth option is available only through the -reporting parameter 
  33. to try, and is primarily for use by Alpha's startup code:
  34.  
  35.     log: display the error message, the error code, and
  36.         whatever context is available through errorInfo in
  37.         either the startup log or the in the Tcl shell, if
  38.         available, after alerting the user to the error.
  39.         
  40.  
  41. _________________________________________________________________
  42.  
  43. EXAMPLES
  44.  
  45.     The script
  46.  
  47.         try {
  48.             error "this is the error" "" "this is the code"
  49.         }
  50.     
  51.     will be reported as follows, depending on the value of 
  52.     errorReporting:
  53.     
  54.         taciturn: reports "this is the error" in the message bar.
  55.         
  56.         terse: reports "this is the error" in a dialog.
  57.         
  58.         verbose: reports
  59.         
  60.                 Message: "this is the error"
  61.                 Error Code: this is the code 
  62.                 
  63.             in a dialog.
  64.             
  65.         pedantic: reports
  66.         
  67.                 Message: "this is the error"
  68.                 Error Code: this is the code
  69.                     # while executing
  70.                 error "this is the error" "" "this is the code"
  71.                     # invoked from within
  72.                 try {error "this is the error" "" "this is the code"}
  73.                 
  74.             in a window (the window is displayed in Tcl mode for better 
  75.             readability). Pedantic reports can get, well, pedantic very 
  76.             quickly, but can be useful guides for debug tracing.
  77.             
  78.         log: reports
  79.         
  80.                 =======================
  81.                 try  error "this is the error" "" "this is the code" error
  82.                 this is the error
  83.                     invoked from within
  84.                 try {error "this is the error" "" "this is the code"}
  85.                 
  86.             in the Tcl shell (or in the startup log).
  87.             
  88.  
  89. In the event that there are errors that you don't wish to display or which to
  90. handle in some special fashion, supply one or more -onError scripts:
  91.  
  92.     try {
  93.         eval $script
  94.     } -onError {
  95.         -34 {error::alertnote "Aughh!!! The disk is full!!!"}
  96.         12* {error::alertnote "VOODOO error: $errorMsg"}
  97.         default {}
  98.     }
  99.     
  100. will display a dialog reporting "Aughh!!!  The disk is full!!!", if you've
  101. executed
  102.  
  103.     set script {error "this is an error" "" "-34"}
  104.  
  105. a dialog reporting "VOODOO error: this is an error" if you've executed
  106.  
  107.     set script {error "this is an error" "" "12005"}
  108.     
  109. and does nothing at all for any other errors; in fact, 
  110.  
  111.     try {
  112.         eval $script
  113.     } -onError {
  114.         default {}
  115.     }
  116.     
  117. is identical to
  118.  
  119.     catch $script
  120.     
  121. (and is, hence, a pretty stupid use of try, since it's noticeably slower). 
  122. Another pointless use of try is
  123.  
  124.     try {
  125.         eval $script
  126.     } -onError {
  127.         default error::rethrow
  128.     }
  129.  
  130. which is identical to
  131.  
  132.     eval $script
  133.  
  134. (not to say that error::rethrow isn't handy, though).
  135.  
  136. Unless explicitly overridden, the default script will display all errors not
  137. accounted for by other -onError scripts.  Always be sure to put the default
  138. script last or none of the other onError scripts will be executed.
  139.  
  140. The above case is OK, but rather than just catching 12000 series VOODOO
  141. errors, it will also catch errorCodes of “123”, “12x”, “12 buckle my shoe”,
  142. and so on.  Better, in this instance, would be to use the -regexp option
  143.  
  144.     try {
  145.         eval $script
  146.     } -onError {
  147.         -34 {error::alertnote "Aughh!!! The disk is full!!!"}
  148.         {12[0-9][0-9][0-9]} {error::alertnote "VOODOO error: $errorMsg"}
  149.         default {}
  150.     } -regexp
  151.     
  152. As usual, the default behavior is clearer; the -regexp behavior is more
  153. powerful.
  154.  
  155.         
  156. A note about alertnotes: I have encountered an intermittent crashing bug,
  157. which arises when an alertnote is displayed while Alpha is in the background. 
  158. As a result, an option is available, both as a user preference and to
  159. individual try calls, to display alertnote messages (terse and verbose
  160. reports) in a small window instead.  Display options are “alertnote always”,
  161. “alertnote preferred”, and “window always”.  Taciturn and pedantic reports
  162. are unaffected by this setting.
  163.  
  164. _________________________________________________________________
  165.  
  166. NAME
  167.     try - Try to execute 'script'. 
  168. SYNOPSIS
  169.     try script ?options?
  170. _________________________________________________________________
  171.  
  172. DESCRIPTION
  173.     The try command executes its script argument in the stack frame that 
  174.     called it.  In the event of an error, try matches the global 
  175.     errorCode against each of any pattern arguments, specified by the 
  176.     -onError parameter, in order.  As soon as it finds a pattern that 
  177.     matches errorCode it evaluates the following body argument by 
  178.     passing it recursively to the Tcl interpreter and returns the 
  179.     result of that evaluation.  The last pattern argument is always a 
  180.     default to display the error (you may explicitly define a default 
  181.     argument if this behavior is not desired). Optionally, the errorMsg 
  182.     can be used for comparison, instead of errorCode.
  183.  
  184.     The syntax is largely that of switch, although the options follow 
  185.     script for both syntactic and performance reasons.  The default 
  186.     comparison mode for try is -glob, instead of -exact.  Unlike 
  187.     switch, try does not support separate pattern/command arguments; 
  188.     all must be provided as a list argument to the -onError optional 
  189.     parameter.  The following options are currently supported:
  190.     
  191.     -onError {pattern body ?pattern body ...?}: errorCode is compared to 
  192.         each pattern in order.  When a match is found, body is 
  193.         executed in the stack frame that called try.  If this option 
  194.         is missing, all errors will be displayed by the default 
  195.         routine.
  196.         
  197.     -exact: Use exact matching when comparing errorCode to a pattern.
  198.  
  199.     -glob: When matching errorCode to the patterns, use glob-style 
  200.         matching (i.e. the same as implemented by the string match 
  201.         command). This is the default.
  202.         
  203.     -regexp: When matching errorCode to the patterns, use regular
  204.         expression matching (i.e. the same as implemented by the regexp 
  205.         command).
  206.         
  207.     -display: Override the user's setting for errorDisplay.
  208.         Options are 'alertnote always', 'alertnote preferred', 
  209.         and 'window always'.
  210.     
  211.     -reporting: Override the user's setting for errorReporting.
  212.         Options are taciturn, terse, verbose, pedantic, and log.
  213.                 
  214.     -while: Short phrase to describe action taking place in event of an 
  215.         error.
  216.     
  217.     -code: Match errorCode against the -onError patterns. This is the 
  218.         default.
  219.         
  220.     -message: Match the errorMsg against the -onError patterns.
  221.  
  222.     The -onError scripts execute in the frame that calls try, so 
  223.     all variables local to that frame are available, as are the global 
  224.     variables errorCode, errorInfo, and errorMsg (without having 
  225.     to declare them global).
  226.     
  227.     If a body is specified as “-” it means that the  body  for
  228.     the  next  pattern  should also be used as the body for this
  229.     pattern (if the next pattern also has a body of  “-”  then
  230.     the body after that is used, and so on).  This feature makes
  231.     it possible to share a single body among several patterns.
  232.  
  233.     Below are some examples of try commands:
  234.  
  235.          try {
  236.              error "" "" aaab
  237.          } -onError {
  238.            ^a.*b$ -
  239.            b {format 1}
  240.            a* {format 2}
  241.            default {format 3}
  242.          } -regexp
  243.     will return 1, and
  244.  
  245.          try {
  246.              error "" "" xyz
  247.          } -onError {
  248.            a
  249.              -
  250.            b
  251.              {format 1}
  252.            a*
  253.              {format 2}
  254.            default
  255.              {format 3}
  256.          }
  257.     will return 3.
  258.     
  259.     NOTE: The old -depth option has been eliminated to allow delayed argument
  260.     processing, resulting in an 80% speed increase for error-free scripts. 
  261.     Instead of 
  262.  
  263.         try {script} -depth n
  264.  
  265.     now use
  266.  
  267.         try::level n {script}
  268.  
  269.     to achieve the same result.
  270.     
  271.     NOTE:
  272.     A 'try' block adds about 0.6 ticks to the execution of an error-free
  273.     script on my 7100/66 so, judiciously applied, there's not much of a penalty 
  274.     in using it. 
  275. _________________________________________________________________
  276.  
  277. NAME
  278.     try::level - Try to execute 'script' at specified 'level'.
  279. SYNOPSIS
  280.     try::level level args
  281. _________________________________________________________________
  282.  
  283. DESCRIPTION
  284.  
  285.     Try to execute a script at a specified level in the execution stack (see 
  286.     uplevel). The remaining arguments are those of try.
  287. _________________________________________________________________
  288.  
  289. NAME
  290.     error::rethrow - Rethrow a caught error
  291. SYNOPSIS
  292.     error::rethrow
  293. _________________________________________________________________
  294.  
  295. DESCRIPTION
  296.  
  297.     In the event that you catch an error you don't wish to handle, call 
  298.     this routine to send the error back to the caller. 
  299.  
  300.  
  301.  
  302. _________________________________________________________________
  303.  
  304. LICENSE AND DISCLAIMER
  305.  
  306. This package is free software; you can redistribute it and/or modify it under
  307. the terms of the GNU General Public License.
  308.  
  309. Author: Jonathan Guyer
  310. E-mail: <jguyer@his.com>
  311.    www: <http://www.his.com/~jguyer/>
  312.  
  313.  Copyright (c) 1998-2000  Jonathan Guyer
  314.  
  315.